<!doctype html>
<html lang="en" class="page-type-section">
<head prefix="og: http://ogp.me/ns#">
<meta charset="utf-8">
<title>日志 - FreeMarker 手册</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="format-detection" content="telephone=no">
<meta property="og:site_name" content="FreeMarker 手册">
<meta property="og:title" content="日志">
<meta property="og:locale" content="en_US">
<meta property="og:url" content="http://freemarker.org/docs/pgui_misc_logging.html">
<link rel="canoical" href="http://freemarker.org/docs/pgui_misc_logging.html">
<link rel="icon" href="favicon.png" type="image/png">
<link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css">
</head>
<body itemscope itemtype="https://schema.org/Code">
    <meta itemprop="url" content="http://freemarker.org/docs/">
    <meta itemprop="name" content="FreeMarker 手册">

  <!--[if lte IE 9]>
  <div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div>
  <![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://freemarker.org" role="banner">            <img itemprop="image" src="logo.png" alt="FreeMarker">
</a><ul class="tabs"><li><a href="http://freemarker.org/">Home</a></li><li class="current"><a href="index.html">Manual</a></li><li><a class="external" href="http://freemarker.org/docs/api/index.html">Java API</a></li></ul><ul class="secondary-tabs"><li><a class="tab icon-heart" href="http://freemarker.org/contribute.html" title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://sourceforge.net/p/freemarker/bugs/new/" title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="http://freemarker.org/freemarkerdownload.html" title="Download"><span>Download</span></a></li></ul></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="toc.html" class="navigation-header">Manual</a><div class="navigation-header"></div></div><div class="site-width breadcrumb-row"><ul class="breadcrumb" itemscope itemtype="http://schema.org/BreadcrumbList"><li class="step-0" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="toc.html"><span itemprop="name">FreeMarker 手册</span></a></li><li class="step-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="pgui.html"><span itemprop="name">程序开发指南</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="pgui_misc.html"><span itemprop="name">其它</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="pgui_misc_logging.html"><span itemprop="name">日志</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><li><a href="alphaidx.html">Alpha. index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions</a></li><li><a href="ref_builtins_alphaidx.html">?builtins</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_specvar.html">.spec_vars</a></li><li><a href="app_faq.html">FAQ</a></li></ul></div></div></div>    <div class="main-content site-width">
      <div class="content-wrapper">
  <div id="table-of-contents-wrapper" class="col-left">
      <script>var breadcrumb = ["FreeMarker 手册","程序开发指南","其它","日志"];</script>
      <script src="toc.js"></script>
      <script src="docgen-resources/main.min.js"></script>
  </div>
<div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="pgui_misc_beanwrapper.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_misc_servlet.html"><span>Next</span></a></div><div class="title-wrapper">
<h1 class="content-header header-section1" id="pgui_misc_logging" itemprop="headline">日志</h1>
</div></div><div class="page-menu">
<div class="page-menu-title">Page Contents</div>
<ul><li><a class="page-menu-link" href="#autoid_54" data-menu-target="autoid_54">日志库选择</a></li><li><a class="page-menu-link" href="#autoid_55" data-menu-target="autoid_55">日志分类</a></li></ul> </div>
          



<h2 class="content-header header-section2" id="autoid_54">日志库选择</h2>


          <p>简而言之，在现代(比如2015年)的应用程序中，
		  记录日志推荐使用SLF4J API。
		  要让 FreeMarker 2.3.x. 使用SLF4J，在项目中加入依赖 
		  <code class="inline-code">org.slf4j:log4j-over-slf4j</code> 即可，
		  要确保 <code class="inline-code">log4j:log4j</code>
		  不能存在。(从 FreeMarker 2.4.x 开始，尽管没有什么害处，
		  但也不再需要 <code class="inline-code">log4j-over-slf4j</code> 了。)</p>

          <p>如果你对这些细节好奇，或者不能使用SLF4J，那么就继续阅读吧...</p>

          <p>FreeMarker 整合了如下的日志包：<a href="http://www.slf4j.org/">SLF4J</a>，<a href="http://commons.apache.org/logging/">Apache Commons Logging</a>，<a href="http://jakarta.apache.org/log4j">Log4J</a> 1.x，<a href="http://jakarta.apache.org/avalon/logkit">Avalon LogKit</a> 和 <a href="http://java.sun.com/j2se/1.4/docs/api/java/util/logging/package-summary.html">
		  <code>java.util.logging</code></a>。默认情况下，
		  FreeMarker(在2.3.x版本下)会按如下顺序来查找日志包，
		  而且会自动使用第一个发现的包：
		  LOG4J(从2.3.22开始，如果正确安装了<code class="inline-code">log4j-over-slf4j</code>，则会使用SLF4J来代替)，
		  Apache Avalon LogKit, <code class="inline-code">java.util.logging</code>。
		  正如你所见，Log4j有最高的优先级。<code class="inline-code">org.apache.log4j.Logger</code> 
		  类会检测Log4j的存在，那么也就是说，像<code class="inline-code">log4j-over-slf4j</code> 或 
          <code class="inline-code">log4j-1.2-api</code>，Log4j重定向也会有最高优先级。</p>

          <p>在 FreeMarker 2.4 版本之前，因为向后兼容性的限制，
		  SLF4J和Apache Commons Logging不会被自动搜索。但是如果你正确安装了 
		  <code class="inline-code">org.slf4j:log4j-over-slf4j</code>(也就意味着，
		  在类路径下没有真实的Log4j，SLF4J有一个像 <code class="inline-code">logback-classic</code> 
		  的支持实现)，那么FreeMarker会直接使用SLF4J API来代替Log4j API
		  (从FreeMarker 2.3.22版本开始)。</p>

          <p>请注意，应用Log4j2日志有个相似的技巧：如果 
		  <code class="inline-code">org.apache.logging.log4j:log4j-1.2-api</code> 可用，
		  FreeMarker 2.3.x会使用它，因为它看起来就像Log4j，
		  但是所有的消息都会自动到Log4j2中。</p>

          <p>如果自动检测没有给出你想要的结果，那么你可以设置系统属性 
          <code class="inline-code">org.freemarker.loggerLibrary</code> 来明确选择
		  (从2.3.22版本开始)一个日志库，比如：</p>

          

<div class="code-wrapper"><pre class="code-block code-unspecified">java <em>...</em> -Dorg.freemarker.loggerLibrary=SLF4J</pre></div>

          <p>系统属性支持的值有：
          <code class="inline-code">SLF4J</code>， <code class="inline-code">CommonsLogging</code>，
          <code class="inline-code">JUL</code> (即 <code class="inline-code">java.util.logging</code>)，
          <code class="inline-code">Avalon</code>， <code class="inline-code">auto</code> (默认行为)， 
		  <code class="inline-code">none</code> (关闭日志)。</p>

          <p>请注意，为了可靠的运行，系统属性应该在JVM启动时(向上面那样)就该设置好，
		  而不是在Java代码之后。</p>

          <p>推荐使用SLF4J，因为它在 FreeMarker 中运行的更好，
		  也是因为从 FreeMarker 2.4 版本开始它有自动检测的最高优先级。</p>
        
          



<h2 class="content-header header-section2" id="autoid_55">日志分类</h2>


          <p>由FreeMarker产生的所有日志信息会被记录到名称由 
		  <code class="inline-code">freemarker.</code>开头的日志记录器中。
		  现在被使用的记录器是：</p>

            <div class="table-responsive">
    <table class="table">

            <thead>
              <tr>
                <th>日志分类名称</th>


                <th>目标</th>

              </tr>

            </thead>


            <tbody>
              <tr>
                <td><code class="inline-code">freemarker.beans</code></td>


                <td>记录Beans包装器模块的日志信息。</td>

              </tr>


              <tr>
                <td><code class="inline-code">freemarker.cache</code></td>


                <td>记录模板加载和缓存相关的日志信息。</td>

              </tr>


              <tr>
                <td><code class="inline-code">freemarker.runtime</code></td>


                <td>记录在模板执行期间的和特定分类无关的相关信息。
				更重要的是，它会记录模板异常并在模板处理期间抛出
				(但它却应该在现行的应用程序中禁用；稍后将会解释)。</td>

              </tr>


              <tr>
                <td><code class="inline-code">freemarker.runtime.attempt</code></td>


                <td>记录在模板执行期间抛出的模板异常日志信息，
				但是是开启DEBUG严重级别，并由 
				<code class="inline-code">attempt</code>/<code class="inline-code">recover</code> 指令捕捉。
				请注意，该异常也会被记录到正常的日志记录器中
				(比如<code class="inline-code">freemarker.runtime</code>)。</td>

              </tr>


              <tr>
                <td><code class="inline-code">freemarker.servlet</code></td>


                <td>记录来自 <code class="inline-code">FreemarkerServlet</code> 类的消息。</td>

              </tr>


              <tr>
                <td><code class="inline-code">freemarker.jsp</code></td>


                <td>记录FreeMarker JSP 支持的消息。</td>

              </tr>

            </tbody>

              </table>
  </div>


          <p>FreeMarker 会在模板执行期间使用 
		  <code class="inline-code">freemarker.runtime</code> 记录异常，即便异常继续增加，最终由 
		  <code class="inline-code">Template.process</code> 或 <code class="inline-code">Environment.process</code> 抛出。
		  (那些都是从应用程序或框架中调用模板时的API调用。)
		  良好的应用程序会记录它们抛出的异常，极少数情况下是处理它们而不去记录日志。
		  但是FreeMarker已经记录了异常，那么就会得到比期望的多一条日志记录。
		  要修复这个问题(从2.3.22版本开始)，可以设置 <code class="inline-code">log_template_exceptions</code>
          (<code class="inline-code">Configurable.setLogTemplateExceptions(boolean)</code>)
          为 <code class="inline-code">false</code>。</p>
        <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="pgui_misc_beanwrapper.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_misc_servlet.html"><span>Next</span></a></div></div></div></div>      </div>
    </div>
<div class="site-footer"><div class="site-width"><div class="footer-top"><div class="col-left sitemap"><div class="column"><h3 class="column-header">Overview</h3><ul><li><a href="http://freemarker.org/index.html">What is FreeMarker?</a></li><li><a href="http://freemarker.org/freemarkerdownload.html">Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="http://freemarker.org/history.html">About us</a></li><li><a itemprop="license" href="app_license.html">License</a></li></ul></div><div class="column"><h3 class="column-header">Handy stuff</h3><ul><li><a href="http://freemarker-online.kenshoo.com/">Try template online</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions cheatsheet</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_builtins_alphaidx.html">?built_ins</a></li><li><a href="ref_specvar.html">.special_vars</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href="https://github.com/nanlei/freemarker/tree/manual-zh-2.3-gae/src/manual">Chinese Manual on Github</a></li><li><a href="https://github.com/freemarker/freemarker">FreeMarker on Github</a></li><li><a href="https://twitter.com/freemarker">Follow us on Twitter</a></li><li><a href="https://sourceforge.net/p/freemarker/bugs/new/">Report a bug</a></li><li><a href="http://stackoverflow.com/questions/ask?tags=freemarker">Ask a question</a></li><li><a href="http://freemarker.org/mailing-lists.html">Mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/freemarker/freemarker">Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker">Twitter</a></li><li><a class="stack-overflow" href="http://stackoverflow.com/questions/ask?tags=freemarker">Stack Overflow</a></li></ul><a class="xxe" href="http://www.xmlmind.com/xmleditor/" rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"><p><span class="generated-for-product">Generated for: Freemarker 2.3.23</span><span class="last-updated"> Last generated:
<time itemprop="dateModified" datetime="2015-09-18T14:38:51Z" title="Friday, September 18, 2015 2:38:51 PM GMT">2015-09-18 14:38:51 GMT</time></span></p> <p class="copyright">
© <span itemprop="copyrightYear">1999</span>–2015
<a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="http://freemarker.org">The FreeMarker Project</a>. All rights reserved. </p>
</div></div></div></body>
</html>
